home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / program / gmp202.zip / README < prev    next >
Text File  |  1996-05-08  |  5KB  |  138 lines
  1.             THE GNU MP LIBRARY
  2.  
  3.  
  4. GNU MP is a library for arbitrary precision arithmetic, operating on signed
  5. integers, rational numbers, and floating point numbers.  It has a rich set
  6. of functions, and the functions have a regular interface.
  7.  
  8. GNU MP is designed to be as fast as possible, both for small operands and for
  9. huge operands.  The speed is achieved by using fullwords as the basic
  10. arithmetic type, by using fast algorithms, by carefully optimized assembly
  11. code for the most common inner loops for a lots of CPUs, and by a general
  12. emphasis on speed (instead of simplicity or elegance).
  13.  
  14. The speed of GNU MP is believed to be faster than any other similar library.
  15. The advantage for GNU MP increases with the operand sizes for certain
  16. operations, since GNU MP in many cases has asymptotically faster algorithms.
  17.  
  18.  
  19.             GETTING STARTED
  20.  
  21. First, you have to configure and compiler GNU MP.  Simply typing
  22.  
  23.     ./configure; make
  24.  
  25. will normally do a reasonable job, but will not give optimal library
  26. execution speed.  So unless you're very unpatient, please read the detailed
  27. instructions in the file INSTALL or in gmp.texi.
  28.  
  29. Once you have compiled the library, you should write some small example, and
  30. make sure you can compile them.  A typical compilation command is this:
  31.  
  32.     gcc -g your-file.c -I<gmp-source-dir> <gmp-bin-dir>libgmp.a -lm
  33.  
  34. If you have installed the library, you can simply do:
  35.  
  36.     gcc -g your-file.c -lgmp -lm
  37.  
  38. The -lm is normally not needed, since only a few functions in GNU MP use the
  39. math library.
  40.  
  41. Here is a sample program that declares 2 variables, initializes them as
  42. required, and sets one of them from a signed integer, and the other from a
  43. string of digits.  It then prints the product of the two numbers in base 10.
  44.  
  45.   #include <stdio.h>
  46.   #include "gmp.h"
  47.  
  48.   main ()
  49.   {
  50.     mpz_t a, b, p;
  51.  
  52.     mpz_init (a);            /* initialize variables */
  53.     mpz_init (b);
  54.     mpz_init (p);
  55.  
  56.     mpz_set_si (a, 756839);        /* assign variables */
  57.     mpz_set_str (b, "314159265358979323846", 0);
  58.     mpz_mul (p, a, b);            /* generate product */
  59.     mpz_out_str (stdout, 10, p);    /* print number without newline */
  60.     puts ("");                /* print newline */
  61.  
  62.     mpz_clear (a);            /* clear out variables */
  63.     mpz_clear (b);
  64.     mpz_clear (p);
  65.  
  66.     exit (0);
  67.   }
  68.  
  69. This might look tedious, with all initializing and clearing.  Fortunately
  70. some of these operations can be combined, and other operations can often be
  71. avoided.  The example above would be written differently by an experienced
  72. GNU MP user:
  73.  
  74.   #include <stdio.h>
  75.   #include "gmp.h"
  76.  
  77.   main ()
  78.   {
  79.     mpz_t b, p;
  80.  
  81.     mpz_init (p);
  82.  
  83.     mpz_init_set_str (b, "314159265358979323846", 0);
  84.     mpz_mul_ui (p, b, 756839);        /* generate product */
  85.     mpz_out_str (stdout, 10, p);    /* print number without newline */
  86.     puts ("");                /* print newline */
  87.  
  88.     exit (0);
  89.   }
  90.  
  91.  
  92.             OVERVIEW OF GNU MP
  93.  
  94. There are five classes of functions in GNU MP.
  95.  
  96.  1. Signed integer arithmetic functions, mpz_*.  These functions are intended
  97.     to be easy to use, with their regular interface.  The associated type is
  98.     `mpz_t'.
  99.  
  100.  2. Rational arithmetic functions, mpq_*.  For now, just a small set of
  101.     functions necessary for basic rational arithmetics.  The associated type
  102.     is `mpq_t'.
  103.  
  104.  3. Floating-point arithmetic functions, mpf_*.  If the C type `double'
  105.     doesn't give enough precision for your application, declare your
  106.     variables as `mpf_t' instead, set the precision to any number desired,
  107.     and call the functions in the mpf class for the arithmetic operations.
  108.  
  109.  4. Positive-integer, hard-to-use, very low overhead functions are in the
  110.     mpn_* class.  No memory management is performed.  The caller must ensure
  111.     enough space is available for the results.  The set of functions is not
  112.     regular, nor is the calling interface.  These functions accept input
  113.     arguments in the form of pairs consisting of a pointer to the least
  114.     significant word, and a integral size telling how many limbs (= words)
  115.     the pointer points to.
  116.  
  117.     Almost all calculations, in the entire package, are made by calling these
  118.     low-level functions.
  119.  
  120.  5. Berkeley MP compatible functions.
  121.  
  122.     To use these functions, include the file "mp.h".  You can test if you are
  123.     using the GNU version by testing if the symbol __GNU_MP__ is defined.
  124.  
  125. For more information on how to use GNU MP, please refer to the documentation.
  126. It is composed from the file gmp.texi, and can be displayed on the screen or
  127. printed.  How to do that, as well how to build the library, is described in
  128. the INSTALL file in this directory.
  129.  
  130.  
  131.             REPORTING BUGS
  132.  
  133. If you find a bug in the library, please make sure to tell us about it!
  134.  
  135. Report bugs and propose modifications and enhancements to
  136. bug-gmp@prep.ai.mit.edu.  What information is needed in a good bug report is
  137. described in the manual.
  138.